from pydantic import BaseModel, Field
from typing import List, Optional


class BarcodeItem(BaseModel):
    """
    函数说明：用于表示单个一维码的结构化信息。

    字段包含：
    - type: 一维码类型（如 EAN13、CODE128 等）
    - data: 解码得到的文本内容
    """
    type: str = Field(..., description="一维码类型，如 EAN13、CODE128 等")
    data: str = Field(..., description="解码得到的文本内容")


class ImageInfo(BaseModel):
    """
    函数说明：用于描述原始图片的关键信息。

    字段包含：
    - filename: 文件名
    - content_type: MIME 类型（例如 image/png、image/jpeg）
    - width: 图片宽度（像素）
    - height: 图片高度（像素）
    - size_bytes: 图片字节大小
    """
    filename: str = Field(..., description="文件名")
    content_type: Optional[str] = Field(None, description="MIME 类型")
    width: int = Field(..., description="图片宽度（像素）")
    height: int = Field(..., description="图片高度（像素）")
    size_bytes: int = Field(..., description="图片大小（字节）")


class PerFileResult(BaseModel):
    """
    函数说明：用于表示单张图片的一维码识别结果。

    字段包含：
    - status: 识别状态（success/failure）
    - barcodes: 识别到的一维码列表
    - image: 原始图片信息
    - error: 错误信息（失败时可选）
    - time_ms: 本图片处理耗时（毫秒）
    """
    status: str = Field(..., description="识别状态（success/failure）")
    barcodes: List[BarcodeItem] = Field(default_factory=list, description="识别到的一维码列表")
    image: ImageInfo = Field(..., description="原始图片信息")
    error: Optional[str] = Field(None, description="错误信息")
    time_ms: Optional[float] = Field(None, description="本图片处理耗时（毫秒）")


class DecodeResponse(BaseModel):
    """
    函数说明：用于表示批量识别的总体响应信息。

    字段包含：
    - status: 总体状态（success/failure）
    - results: 每个图片的识别结果列表
    - processing_time_ms: 总体处理耗时（毫秒）
    """
    status: str = Field(..., description="总体状态（success/failure）")
    results: List[PerFileResult] = Field(..., description="每个图片的识别结果列表")
    processing_time_ms: float = Field(..., description="总体处理耗时（毫秒）")